其實 UI 還沒有完全結束，但因鐵人賽時長的限制，UI 的設計會告一段落。剩餘的天數將用來處理後端的部分。我們今天先使用 RESTful API 來設計我們的聊天 APP ─ Whisper

登入、登出

註冊新用戶

Path: /api/v1/users
Method: POST
Request:
	- name					string "使用者名稱"
	- user					string "帳號"
	- password				string "密碼"
	- email					string "Email"
	- pin 					string "恢復 private key 用的 pin 碼"
	- public_key			string
	- encrypted_private_key	string "透過 pin 碼加密儲存在伺服器"
Response:
	success:
		- 201 Created 
	fail:
		- 400 Bad Request 請求格式不正確
		- 422 Unprocessable Entity 使用者名稱已存在
		- 500 Internal Server Error 伺服器端發生錯誤
	content:
		- error string

登入

Path: /api/v1/auth/login
Method: POST
Request:
	- user		string "使用者名稱"
	- password	string "密碼"
Response:
	success:
		- 200 OK
	fail:
		- 401 Unauthorized 驗證失敗
		- 500 Internal Server Error 伺服器端發生錯誤
	content:
		- token	string "權杖"
		- error	string

登出

Path: /api/v1/auth/logout
Method: POST
Header:
	- Authorization
Response:
	success:
		- 204 No Content
	fail:
		- 500 Internal Server Error 伺服器端發生錯誤
	content:
		- error	string

管理個人資料

取得 me 基本資料

Path: /api/v1/me
Method: GET
Header:
	- Authorization
Response:
	success:
		- 200 OK
	fail:
		- 401 Unauthorized 認證失敗
		- 500 Internal Server Error 伺服器端發生錯誤
	content:
		- error			string
		- uid			int
		- user			string "帳號"
		- name			string
		- profile		string "頭貼的 url"
		- email			string
		- public_key	string

取得用 PIN 加密過的 private key

Path: /api/v1/me/key
Method: Get
Header:
	- Authorization
	- Pin
Response:
	success:
		- 200 OK
	fail:
		- 401 Unauthorized 驗證失敗 (Token 或 pin 碼)
		- 500 Internal Server Error 伺服器端發生錯誤
	content:
		- error					string
		- encrypted_private_key	string

伺服器利用 pin 碼加鹽雜湊確定 pin 碼為真，回傳透過 pin 碼加密儲存在伺服器的私鑰

更新用戶資料

Path: /api/v1/users/me
Method: PUT
Header:
	- Authorization
Request:
	- email   (optional)
	- user    (optional)
	- name    (optional)
	- profile (optional)
Response:
	success:
		 - 200 OK
	fail:
		- 400 Bad Request 請求格式錯誤
		- 401 Unauthorized 未經授權
		- 409 Conflict 更新衝突 e.g. Email 已被使用
		- 500 Internal Server Error 伺服器端發生錯誤
	content:
		- error string

處理加密用的 pin 碼、public id 更新上有點複雜，不實作

用戶基本資料

取得任意用戶基本資料

Path: /api/v1/users/:uid
Method: GET
Response:
	success:
		- 200 OK
	fail:
		- 404 Not Found 用戶不存在
		- 500 Internal Server Error 伺服器端發生錯誤
	content:
		- error 		string
		- uid   		int
		- user  		string
		- name  		string
		- profile		string "頭貼的 url"
		- public_key	string

好友管理

新增好友

Path: /api/v1/friends
Method: POST
Header:
	- Authorization
Request:
	- user	string
Response:
	success:
		- 201 Created 
	fail:
		- 400 Bad Request 請求格式不正確
		- 401 Unauthorized 未經授權
		- 404 Not Found 用戶 uid 不存在
		- 409 Conflict 已經是好友了
		- 500 Internal Server Error 伺服器端發生錯誤
	content:
		- error string

移除好友

Path: /api/v1/friends/:uid
Method: DELETE
Header:
	- Authorization
Response:
	success:
		- 204 No Content 刪除成功
	fail:
		- 401 Unauthorized 未經授權
		- 500 Internal Server Error 伺服器端發生錯誤
	content:
		- error string

取得朋友列表

Path: /api/v1/friends/:from
Method: GET
Header:
	- Authorization
Response:
	success:
		- 200 OK
	fail:
	    - 400 Bad Request 請求格式不正確
		- 401 Unauthorized 未經授權
		- 500 Internal Server Error 伺服器端發生錯誤
	content:
		- error		string
		- next		bool	"-1 代表無下一筆"
		- list:
			- uid			int
			- user			string
			- name			string
			- profile		string
			- public_key	string
			- channel_id	int			"-1 代表不存在"

聊天室

資料庫裡面大概會長這樣

- channel_id (primary key)
- user_a
- user_b
- key_encrypted_by_user_a	(a 可利用私鑰得到聊天室的鎖)
- key_encrypted_by_user_b	(b 可利用私鑰得到聊天室的鎖)

建立聊天室

Path: /api/v1/channels
Method: POST
Header:
	- Authorization
Request:
	- attendee  							int     (朋友的 id)
	- key_encrypted_by_attendee_public_key	string
	- key_encrypted_by_host_public_key		string
Response:
	success:
		- 201 Created 
	fail:
		- 400 Bad Request 請求格式不正確
		- 401 Unauthorized 未經授權
		- 409 Conflict 聊天室已存在
		- 500 Internal Server Error 伺服器端發生錯誤
	content:
		- channel_id	int

建立聊天室的用戶，必需先自行生成一組 key 值，並用對方的 public key 做加密告訴對方

取得聊天室金鑰

Path: /api/v1/channels/key/:channel_id
Method: GET
Header:
	- Authorization
Response:
	success:
		- 200 OK
    fail:
    	- 400 Bad Request 請求格式不正確
		- 401 Unauthorized 未經授權
		- 403 Forbidden 無法存取該聊天室
		- 500 Internal Server Error 伺服器端發生錯誤
	content:
	    - error				string
		- encrypted_key		string

傳送訊息

Path: /api/v1/messages/:channel_id
Method: POST
Header:
	- Authorization
Request:
	- encrypted_msg		string
Response:
	success:
		- 200 OK
    fail:
    	- 400 Bad Request 請求格式不正確
		- 401 Unauthorized 未經授權
		- 403 Forbidden 無法存取該聊天室
		- 500 Internal Server Error 伺服器端發生錯誤
	content:
		- error			string
		- message_id	int

取得聊天室聊天內容

Path: /api/v1/messages/:channel_id/:next
Method: GET
Header:
	- Authorization
Response:
	success:
		- 200 OK
	fail:
		- 400 Bad Request 請求格式不正確
		- 401 Unauthorized 未經授權
		- 403 Forbidden 無法存取該聊天室
		- 500 Internal Server Error 伺服器端發生錯誤
	content:
		- error					string
		- next					int		(-1 表示無下一筆)
		- list:
			- encrypted_msg		string
			- sender			int
			- time				int

取得聊天室列表

Path: /api/v1/channels/:next
Method: GET
Header:
	- Authorization
Response:
	success:
		- 200 OK
	fail:
		- 400 Bad Request 請求格式不正確
		- 401 Unauthorized 未經授權
		- 500 Internal Server Error 伺服器端發生錯誤
	content:
		- error		string
		- next		int				(-1 代表無下一筆)
		- list:
			- channel_id			int
			- attendee				int	   (朋友的 id)
			- attendee_profile		string (朋友的頭貼)
			- encrypted_key			string (用自己的公鑰加密的 key)
			- last_encrypted_msg	string (已加密的最新訊息)